User's Choice Windows CD/User's Choice Windows CD (CMS Software)(1993).iso/utility2/wine02bx.zip/INFO/EMACS.12

Text File | 1993-03-28 | 49KB | 1,177 lines

Info file ../info/emacs, produced by Makeinfo, -*- Text -*- from input
file lemacs.tex.

   This file documents the GNU Emacs editor.

   Copyright (C) 1985, 1986, 1988 Richard M. Stallman.  Copyright (C)
1991, 1992 Lucid, Inc.

   Permission is granted to make and distribute verbatim copies of
this manual provided the copyright notice and this permission notice
are preserved on all copies.

   Permission is granted to copy and distribute modified versions of
this manual under the conditions for verbatim copying, provided also
that the sections entitled "The GNU Manifesto", "Distribution" and "GNU
General Public License" are included exactly as in the original, and
provided that the entire resulting derived work is distributed under
the terms of a permission notice identical to this one.

   Permission is granted to copy and distribute translations of this
manual into another language, under the above conditions for modified
versions, except that the sections entitled "The GNU Manifesto",
"Distribution" and "GNU General Public License" may be included in a
translation approved by the author instead of in the original English.


File: emacs,  Node: Sorting,  Next: Shell,  Prev: Narrowing,  Up: Top

Sorting Text
============

   Emacs provides several commands for sorting text in a buffer.  All
operate on the contents of the region (the text between point and the
mark).  They divide the text of the region into many "sort records",
identify a "sort key" for each record, and then reorder the records
using the order determined by the sort keys.  The records are ordered
so that their keys are in alphabetical order, or, for numeric sorting,
in numeric order.  In alphabetic sorting, all upper case letters `A'
through `Z' come before lower case `a', in accord with the ASCII
character sequence.

   The sort commands differ in how they divide the text into sort
records and in which part of each record they use as the sort key.
Most of the commands make each line a separate sort record, but some
commands use paragraphs or pages as sort records.  Most of the sort
commands use each entire sort record as its own sort key, but some use
only a portion of the record as the sort key.

`M-x sort-lines'
     Divide the region into lines, and sort by comparing the entire
     text of a line.  A prefix argument means sort in descending order.

`M-x sort-paragraphs'
     Divide the region into paragraphs and sort by comparing the entire
     text of a paragraph (except for leading blank lines).  A prefix
     argument means sort in descending order.

`M-x sort-pages'
     Divide the region into pages, and sort by comparing the entire
     text of a page (except for leading blank lines).  A prefix
     argument means sort in descending order.

`M-x sort-fields'
     Divide the region into lines, and sort by comparing the contents
     of one field in each line.  Fields are defined as separated by
     whitespace, so the first run of consecutive non-whitespace
     characters in a line constitutes field 1, the second such run
     constitutes field 2, etc.

     You specify which field to sort by with a numeric argument: 1 to
     sort by field 1, etc.  A negative argument means sort in
     descending order.  Thus, minus 2 means sort by field 2 in
     reverse-alphabetical order.

`M-x sort-numeric-fields'
     Like `M-x sort-fields' except the specified field is converted to
     a number for each line, and the numbers are compared.  `10' comes
     before `2' when considered as text, but after it when considered
     as a number.

`M-x sort-columns'
     Like `M-x sort-fields' except that the text within each line used
     for comparison comes from a fixed range of columns.  An
     explanation is given below.

   For example, if the buffer contains

     On systems where clash detection (locking of files being edited) is
     implemented, Emacs also checks the first time you modify a buffer
     whether the file has changed on disk since it was last visited or
     saved.  If it has, you are asked to confirm that you want to change
     the buffer.

then if you apply `M-x sort-lines' to the entire buffer you get

     On systems where clash detection (locking of files being edited) is
     implemented, Emacs also checks the first time you modify a buffer
     saved.  If it has, you are asked to confirm that you want to change
     the buffer.
     whether the file has changed on disk since it was last visited or

where the upper case `O' comes before all lower case letters.  If you
apply instead `C-u 2 M-x sort-fields' you get

     implemented, Emacs also checks the first time you modify a buffer
     saved.  If it has, you are asked to confirm that you want to change
     the buffer.
     On systems where clash detection (locking of files being edited) is
     whether the file has changed on disk since it was last visited or

where the sort keys were `Emacs', `If', `buffer', `systems' and `the'.

   `M-x sort-columns' requires more explanation.  You specify the
columns by putting point at one of the columns and the mark at the
other column.  Because this means you cannot put point or the mark at
the beginning of the first line to sort, this command uses an unusual
definition of `region': all of the line point is in is considered part
of the region, and so is all of the line the mark is in.

   For example, to sort a table by information found in columns 10 to
15, you could put the mark on column 10 in the first line of the
table, and point on column 15 in the last line of the table, and then
use this command.  Or you could put the mark on column 15 in the first
line and point on column 10 in the last line.

   This can be thought of as sorting the rectangle specified by point
and the mark, except that the text on each line to the left or right
of the rectangle moves along with the text inside the rectangle.
*Note Rectangles::.


File: emacs,  Node: Shell,  Next: Hardcopy,  Prev: Sorting,  Up: Top

Running Shell Commands from Emacs
=================================

   Emacs has commands for passing single command lines to inferior
shell processes; it can also run a shell interactively with input and
output to an Emacs buffer `*shell*'.

`M-!'
     Run a specified shell command line and display the output
     (`shell-command').

`M-|'
     Run a specified shell command line with region contents as input;
     optionally replace the region with the output
     (`shell-command-on-region').

`M-x shell'
     Run a subshell with input and output through an Emacs buffer.
     You can then give commands interactively.

* Menu:

* Single Shell::         How to run one shell command and return.
* Interactive Shell::    Permanent shell taking input via Emacs.
* Shell Mode::           Special Emacs commands used with permanent shell.


File: emacs,  Node: Single Shell,  Next: Interactive Shell,  Prev: Shell,  Up: Shell

Single Shell Commands
---------------------

   `M-!' (`shell-command') reads a line of text using the minibuffer
and creates an inferior shell to execute the line as a command.
Standard input from the command comes from the null device.  If the
shell command produces any output, the output goes to an Emacs buffer
named `*Shell Command Output*', which is displayed in another window
but not selected.  A numeric argument, as in `M-1 M-!', directs this
command to insert any output into the current buffer.  In that case,
point is left before the output and the mark is set after the output.

   `M-|' (`shell-command-on-region') is like `M-!' but passes the
contents of the region as input to the shell command, instead of no
input.  If a numeric argument is used to direct  output to the current
buffer, then the old region is deleted first and the output replaces
it as the contents of the region.

   Both `M-!' and `M-|' use `shell-file-name' to specify the shell to
use.  This variable is initialized based on your `SHELL' environment
variable when you start Emacs.  If the file name does not specify a
directory, the directories in the list `exec-path' are searched; this
list is initialized based on the `PATH' environment variable when you
start Emacs.  You can override either or both of these default
initializations in your `.emacs' file .

   When you use `M-!' and `M-|', Emacs has to wait until the shell
command completes.  You can quit with `C-g'; that terminates the shell
command.


File: emacs,  Node: Interactive Shell,  Next: Shell Mode,  Prev: Single Shell,  Up: Shell

Interactive Inferior Shell
--------------------------

   To run a subshell interactively with its typescript in an Emacs
buffer, use `M-x shell'.  This creates (or reuses) a buffer named
`*shell*' and runs a subshell with input coming from and output going
to that buffer.  That is to say, any "terminal output" from the
subshell will go into the buffer, advancing point, and any "terminal
input" for the subshell comes from text in the buffer.  To give input
to the subshell, go to the end of the buffer and type the input,
terminated by RET.

   Emacs does not wait for the subshell to do anything.  You can switch
windows or buffers and edit them while the shell is waiting, or while
it is running a command.  Output from the subshell waits until Emacs
has time to process it; this happens whenever Emacs is waiting for
keyboard input or for time to elapse.

   To get multiple subshells, change the name of buffer `*shell*' to
something different by using `M-x rename-buffer'.  The next use of
`M-x shell' creates a new buffer `*shell*' with its own subshell.  By
renaming this buffer as well you can create a third one, and so on.
All the subshells run independently and in parallel.

   The file name used to load the subshell is the value of the variable
`explicit-shell-file-name', if that is non-`nil'.  Otherwise, the
environment variable `ESHELL' is used, or the environment variable
`SHELL' if there is no `ESHELL'.  If the file name specified is
relative, the directories in the list `exec-path' are searched (*note
Single Shell Commands: Single Shell.).

   As soon as the subshell is started, it is sent as input the
contents of the file `~/.emacs_SHELLNAME', if that file exists, where
SHELLNAME is the name of the file that the shell was loaded from.  For
example, if you use `csh', the file sent to it is `~/.emacs_csh'.

   `cd', `pushd' and `popd' commands given to the inferior shell are
watched by Emacs so it can keep the `*shell*' buffer's default
directory the same as the shell's working directory.  These commands
are recognized syntactically by examining lines of input that are
sent.  If you use aliases for these commands, you can tell Emacs to
recognize them also.  For example, if the value of the variable
`shell-pushd-regexp' matches the beginning of a shell command line,
that line is regarded as a `pushd' command.  Change this variable when
you add aliases for `pushd'.  Likewise, `shell-popd-regexp' and
`shell-cd-regexp' are used to recognize commands with the meaning of
`popd' and `cd'.

   `M-x shell-resync-dirs' queries the shell and resynchronizes Emacs'
idea of what the current directory stack is.  `M-x
shell-dirtrack-toggle' turns directory tracking on and off.

   Emacs keeps a history of the most recent commands you have typed in
the `*shell*' buffer.  If you are at the beginning of a shell command
line and type M-p, the previous shell input is inserted into the
buffer before point.  Immediately typing M-p again deletes that input
and inserts the one before it.  By repeating M-p you can move backward
through your commands until you find one you want to repeat.  You may
then edit the command before typing RET if you wish. M-n moves forward
through the command history, in case you moved backward past the one
you wanted while using M-p.  If you type the first few characters of a
previous command and then type M-p, the most recent shell input
starting with those characters is inserted.  This can be very
convenient when you are repeating a sequence of shell commands.  The
variable `input-ring-size' controls how many commands are saved in
your input history.  The default is 30.


File: emacs,  Node: Shell Mode,  Prev: Interactive Shell,  Up: Shell

Shell Mode
----------

   The shell buffer uses Shell mode, which defines several special keys
attached to the `C-c' prefix.  They are chosen to resemble the usual
editing and job control characters present in shells that are not under
Emacs, except that you must type `C-c' first.  Here is a list of the
special key bindings of Shell mode:

`RET'
     At end of buffer send line as input; otherwise, copy current line
     to end of buffer and send it (`send-shell-input').  When a line
     is copied, any text at the beginning of the line that matches the
     variable `shell-prompt-pattern' is left out; this variable's
     value should be a regexp string that matches the prompts that you
     use in your subshell.

`C-c C-d'
     Send end-of-file as input, probably causing the shell or its
     current subjob to finish (`shell-send-eof').

`C-d'
     If point is not at the end of the buffer, delete the next
     character just like most other modes.  If point is at the end of
     the buffer, send end-of-file as input (instead of generating an
     error as in other modes).

`C-c C-u'
     Kill all text that has yet to be sent as input
     (`kill-shell-input').

`C-c C-w'
     Kill a word before point (`backward-kill-word').

`C-c C-c'
     Interrupt the shell or its current subjob if any
     (`interrupt-shell-subjob').

`C-c C-z'
     Stop the shell or its current subjob if any (`stop-shell-subjob').

`C-c C-\'
     Send quit signal to the shell or its current subjob if any
     (`quit-shell-subjob').

`C-c C-o'
     Delete last batch of output from shell (`kill-output-from-shell').

`C-c C-r'
     Scroll top of last batch of output to top of window
     (`show-output-from-shell').

`C-c C-y'
     Copy the previous bunch of shell input, and insert it into the
     buffer before point (`copy-last-shell-input').  No final newline
     is inserted, and the input copied is not resubmitted until you
     type RET.

`M-p'
     Move backward through the input history.  Search for a matching
     command if you have typed the beginning of a command.

`M-n'
     Move forward through the input history.  Useful when you are
     using M-p quickly and go past the desired command.

`TAB'
     Complete the file name preceding point.


File: emacs,  Node: Hardcopy,  Next: Dissociated Press,  Prev: Shell,  Up: Top

Hardcopy Output
===============

   The Emacs commands for making hardcopy derive their names from the
Unix commands `print' and `lpr'.

`M-x print-buffer'
     Print hardcopy of current buffer using Unix command `print'
     (`lpr -p').  This command adds page headings containing the file
     name and page number.

`M-x lpr-buffer'
     Print hardcopy of current buffer using Unix command `lpr'.  This
     command does not add page headings.

`M-x print-region'
     Like `print-buffer' but prints only the current region.

`M-x lpr-region'
     Like `lpr-buffer' but prints only the current region.

   All the hardcopy commands pass extra switches to the `lpr' program
based on the value of the variable `lpr-switches'.  Its value should
be a list of strings, each string a switch starting with `-'.  For
example, the value could be `("-Pfoo")' to print on printer `foo'.


File: emacs,  Node: Dissociated Press,  Next: CONX,  Prev: Hardcopy,  Up: Top

Dissociated Press
=================

   `M-x dissociated-press' is a command for scrambling a file of text
either word by word or character by character.  Starting from a buffer
of straight English, it produces extremely amusing output.  The input
comes from the current Emacs buffer.  Dissociated Press writes its
output in a buffer named `*Dissociation*', and redisplays that buffer
after every couple of lines (approximately) to facilitate reading it.

   `dissociated-press' asks every so often whether to continue
operating.  Answer `n' to stop it.  You can also stop at any time by
typing `C-g'.  The dissociation output remains in the `*Dissociation*'
buffer for you to copy elsewhere if you wish.

   Dissociated Press operates by jumping at random from one point in
the buffer to another.  In order to produce plausible output rather
than gibberish, it insists on a certain amount of overlap between the
end of one run of consecutive words or characters and the start of the
next.  That is, if it has just printed out `president' and then
decides to jump to a different point in the file, it might spot the
`ent' in `pentagon' and continue from there, producing
`presidentagon'.  Long sample texts produce the best results.

   A positive argument to `M-x dissociated-press' tells it to operate
character by character, and specifies the number of overlap
characters.  A negative argument tells it to operate word by word and
specifies the number of overlap words.  In this mode, whole words are
treated as the elements to be permuted, rather than characters.  No
argument is equivalent to an argument of two.  For your
againformation, the output goes only into the buffer `*Dissociation*'.
 The buffer you start with is not changed.

   Dissociated Press produces nearly the same results as a Markov chain
based on a frequency table constructed from the sample text.  It is,
however, an independent, ignoriginal invention.  Dissociated Press
techniquitously copies several consecutive characters from the sample
between random choices, whereas a Markov chain would choose randomly
for each word or character.  This makes for more plausible sounding
results, and runs faster.

   It is a mustatement that too much use of Dissociated Press can be a
developediment to your real work.  Sometimes to the point of outragedy.
And keep dissociwords out of your documentation, if you want it to be
well userenced and properbose.  Have fun.  Your buggestions are
welcome.


File: emacs,  Node: CONX,  Next: Amusements,  Prev: Dissociated Press,  Up: Top

CONX
====

   Besides producing a file of scrambled text with Dissociated Press,
you can generate random sentences by using CONX.

`M-x conx'
     Generate random sentences in the *conx* buffer.

`M-x conx-buffer'
     Absorb the text in the current buffer into the `conx' database.

`M-x conx-init'
     Forget the current word-frequency tree.

`M-x conx-load'
     Load a `conx' database that has been previously saved with `M-x
     conx-save'.

`M-x conx-region'
     Absorb the text in the current buffer into the conx database.

`M-x conx-save'
     Save the current conx database to a file for future retrieval.

   Copy text from a buffer using `M-x conx-buffer' or `M-x conx-region'
and then type `M-x conx'.  Output is continuously generated until you
type ^G. You can save the `conx' database to a file with `M-x
conx-save', which you can retrieve with `M-x conx-load'.  To clear the
database, use `M-x conx-init'.


File: emacs,  Node: Amusements,  Next: Emulation,  Prev: CONX,  Up: Top

Other Amusements
================

   If you are a little bit bored, you can try `M-x hanoi'.  If you are
considerably bored, give it a numeric argument.  If you are very very
bored, try an argument of 9.  Sit back and watch.

   When you are frustrated, try the famous Eliza program.  Just do
`M-x doctor'.  End each input by typing `RET' twice.

   When you are feeling strange, type `M-x yow'.


File: emacs,  Node: Emulation,  Next: Customization,  Prev: Amusements,  Up: Top

Emulation
=========

   GNU Emacs can be programmed to emulate (more or less) most other
editors.  Standard facilities can emulate these:

EDT (DEC VMS editor)
     Turn on EDT emulation with `M-x edt-emulation-on'.  `M-x
     edt-emulation-off' restores normal Emacs command bindings.

     Most of the EDT emulation commands are keypad keys, and most
     standard Emacs key bindings are still available.  The EDT
     emulation rebindings are done in the global keymap, so there is
     no problem switching buffers or major modes while in EDT
     emulation.

Gosling Emacs
     Turn on emulation of Gosling Emacs (aka Unipress Emacs) with `M-x
     set-gosmacs-bindings'.  This redefines many keys, mostly on the
     `C-x' and `ESC' prefixes, to work as they do in Gosmacs.  `M-x
     set-gnu-bindings' returns to normal GNU Emacs by rebinding the
     same keys to the definitions they had at the time `M-x
     set-gosmacs-bindings' was done.

     It is also possible to run Mocklisp code written for Gosling
     Emacs.  *Note Mocklisp::.

evi (vi emulation in Lucid GNU Emacs)
     In Lucid GNU Emacs, evi is the emulation of vi within Emacs.  By
     default, evi-mode is as close as possible to regular vi.  To
     start evi mode from Emacs, type: `Meta-x evi'.

     If you want be in evi mode whenever you bring up Emacs, include
     this line in your `.emacs' file:

          (setq term-setup-hook 'evi)

          *Note evi Mode:: for more information on evi Mode.

vi (Berkeley Unix editor)
     Turn on vi emulation with `M-x vi-mode'.  This is a major mode
     that replaces the previously established major mode.  All of the
     vi commands that, in real vi, enter "input" mode are programmed
     in the Emacs emulator to return to the previous major mode.  Thus,
     ordinary Emacs serves as vi's "input" mode.

     Because vi emulation works through major modes, it does not work
     to switch buffers during emulation.  Return to normal Emacs first.

     If you plan to use vi emulation much, you probably want to bind a
     key to the `vi-mode' command.

vi (alternate emulator)
     Another vi emulator said to resemble real vi more thoroughly is
     invoked by `M-x vip-mode'.  "Input" mode in this emulator is
     changed from ordinary Emacs so you can use ESC to go back to
     emulated vi command mode.  To get from emulated vi command mode
     back to ordinary Emacs, type `C-z'.

     This emulation does not work through major modes, and it is
     possible to switch buffers in various ways within the emulator.
     It is not so necessary to assign a key to the command `vip-mode'
     as it is with `vi-mode' because terminating insert mode does not
     use it.

     For full information, see the long comment at the beginning of the
     source file, which is `lisp/vip.el' in the Emacs distribution.

   Warning: loading more than one vi emulator at once may cause name
conficts; no one has checked.

* Menu:

* evi Mode:: Brief discussion of evi, the vi Emulation mode within Lucid
             GNU Emacs


File: emacs,  Node: evi Mode,  Prev: Emulation,  Up: Emulation

Using evi Mode
--------------

   In Lucid GNU Emacs, evi provides vi emulation within Emacs.  By
default, evi-mode is as close as possible to regular vi.  To start evi
mode from Emacs, type: `Meta-x evi' If you want be in evi mode
whenever you bring up Emacs, include this line in your `.emacs' file:

     (setq term-setup-hook 'evi)

   You can find a customization file for evi-mode in `~/.evirc'.  This
file has to contain Lisp code, just like the `.emacs' file, and is
loaded whenever you invoke evi mode.  The file allows you to rebind
keys in evi mode, just as you can in other Emacs modes.

   Note that evi also loads a file of vi commands from `.exrc', just
like vi.

   By default, all Emacs commands are disabled in evi mode.  This
leaves you with only vi commands.  You may customize evi mode to make
certain keybindings accessible.  For example, to enable all emacs
command sequences that begin with `Control-x' or with `Meta', include
the following lines in your `.evirc' file:

     (evi-define-key evi-all-keymaps "\C-x" ctl-x-map)
     (setq evi-meta-prefix-char ?\C-a)
     (evi-define-key evi-all-keymaps "\C-a" esc-map)

   When you are in evi mode, typing `Control-z' stops vi emulation,
leaving you in Emacs.  To get back into evi mode, use `Meta-x evi'
again.  To exit Emacs, use `Control-x Control-c'.

   The file management commands used by vi have been adapted to Emacs.
They have slightly different meanings than the vi commands itself:

`:e'
     Edit a file in the current window.  With no argument, brings in a
     new copy of the file, if it has been subsequently modified on
     disk.  `:e' overrides any complaints about the current buffer
     being modified and discards all modifications.  With a filename
     argument, it edits that file in the current window, using the
     copy already in the editor if it was previously read in.  There
     is no difference between `:e!  filename' and `:e filename'.  As a
     shorthand for editing the most recently accessed buffer not in
     the window, use `:e#'.

`:E'
     Same as `:e', but edits the file in another window, creating that
     window if necessary.  If used with no filename, this command
     splits the current buffer into two windows.

`:n'
     Switch to the next file in the buffer list that is not currently
     displayed.  Rotates the current file to the end of the buffer
     list, so the command effectively cycles through all buffers.

`:N'
     Same as `:n', but switches to another window or creates another
     window and puts the next file into it.

   All `ex' commands that accept filenames as arguments perform file
completion using `Space' or `Tab'.  Completion begins after the space
that separates the command from the filename.

   Many of the `ex' commands are not implemented.  The following
commands are implemented:

     cd, chdir, copy, delete, edit, file, global, map, move, next print,
     put, quit, read, set, source, substitute, tag, write, wq, yank, !, <, >

   The following `ex' options are implemented:

     autoindent, ignorecase, magic, notimeout, shiftwidth, showmatch,
     tabstop, wrapscan


File: emacs,  Node: Customization,  Next: Quitting,  Prev: Emulation,  Up: Top

Customization
*************

   This chapter talks about various topics relevant to adapting the
behavior of Emacs in minor ways.

   All kinds of customization affect only the particular Emacs job
that you do them in.  They are completely lost when you kill the Emacs
job, and have no effect on other Emacs jobs you may run at the same
time or later.  The only way an Emacs job can affect anything outside
of it is by writing a file; in particular, the only way to make a
customization `permanent' is to put something in your `.emacs' file or
other appropriate file to do the customization in each session.  *Note
Init File::.

* Menu:

* Minor Modes::     Each minor mode is one feature you can turn on
                     independently of any others.
* Variables::       Many Emacs commands examine Emacs variables
                     to decide what to do; by setting variables,
                     you can control their functioning.
* Keyboard Macros:: A keyboard macro records a sequence of keystrokes
                     to be replayed with a single command.
* Key Bindings::    The keymaps say what command each key runs.
                     By changing them, you can "redefine keys".
* Syntax::          The syntax table controls how words and expressions
                     are parsed.
* Init File::       How to write common customizations in the `.emacs'
                     file.
* Audible Bell::    Changing how Emacs sounds the bell.
* Faces::
                    Changing the fonts and colors of a region of text.


File: emacs,  Node: Minor Modes,  Next: Variables,  Up: Customization

Minor Modes
===========

   Minor modes are options which you can use or not.  For example, Auto
Fill mode is a minor mode in which SPC breaks lines between words as
you type.  All the minor modes are independent of each other and of
the selected major mode.  Most minor modes inform you in the mode line
when they are on; for example, `Fill' in the mode line means that Auto
Fill mode is on.

   Append `-mode' to the name of a minor mode to get the name of a
command function that turns the mode on or off.  Thus, the command to
enable or disable Auto Fill mode is called `M-x auto-fill-mode'.  These
commands are usually invoked with `M-x', but you can bind keys to them
if you wish.  With no argument, the function turns the mode on if it
was off and off if it was on.  This is known as "toggling".  A positive
argument always turns the mode on, and an explicit zero argument or a
negative argument always turns it off.

   Auto Fill mode allows you to enter filled text without breaking
lines explicitly.  Emacs inserts newlines as necessary to prevent
lines from becoming too long.  *Note Filling::.

   Overwrite mode causes ordinary printing characters to replace
existing text instead of moving it to the right.  For example, if
point is in front of the `B' in `FOOBAR', and you type a `G' in
Overwrite mode, it changes to `FOOGAR', instead of `FOOGBAR'.

   Abbrev mode allows you to define abbreviations that automatically
expand as you type them.  For example, `amd' might expand to `abbrev
mode'.  *Note Abbrevs::, for full information.


File: emacs,  Node: Variables,  Next: Keyboard Macros,  Prev: Minor Modes,  Up: Customization

Variables
=========

   A "variable" is a Lisp symbol which has a value.  The symbol's name
is also called the name of the variable.  Variable names can contain
any characters, but conventionally they are chosen to be words
separated by hyphens.  A variable can have a documentation string
which describes what kind of value it should have and how the value
will be used.

   Lisp allows any variable to have any kind of value, but most
variables that Emacs uses require a value of a certain type.  Often
the value has to be a string, or has to be a number.  Sometimes we say
that a certain feature is turned on if a variable is "non-`nil',"
meaning that if the variable's value is `nil', the feature is off, but
the feature is on for any other value.  The conventional value to turn
on the feature--since you have to pick one particular value when you
set the variable--is `t'.

   Emacs uses many Lisp variables for internal recordkeeping, as any
Lisp program must, but the most interesting variables for you are the
ones that exist for the sake of customization.  Emacs does not
(usually) change the values of these variables; instead, you set the
values, and thereby alter and control the behavior of certain Emacs
commands.  These variables are called "options".  Most options are
documented in this manual, and appear in the Variable Index (*note
Variable Index::.).

   One example of a variable which is an option is `fill-column', which
specifies the position of the right margin (as a number of characters
from the left margin) to be used by the fill commands (*note
Filling::.).

* Menu:

* Examining::           Examining or setting one variable's value.
* Edit Options::        Examining or editing list of all variables' values.
* Locals::              Per-buffer values of variables.
* File Variables::      How files can specify variable values.


File: emacs,  Node: Examining,  Next: Edit Options,  Prev: Variables,  Up: Variables

Examining and Setting Variables
-------------------------------

`C-h v'
`M-x describe-variable'
     Print the value and documentation of a variable.

`M-x set-variable'
     Change the value of a variable.

   To examine the value of a single variable, use `C-h v'
(`describe-variable'), which reads a variable name using the
minibuffer, with completion.  It prints both the value and the
documentation of the variable.

     C-h v fill-column RET

prints something like

     fill-column's value is 75

     Documentation:
     *Column beyond which automatic line-wrapping should happen.
     Automatically becomes local when set in any fashion.

The star at the beginning of the documentation indicates that this
variable is an option.  `C-h v' is not restricted to options; it
allows any variable name.

   If you know which option you want to set, you can use `M-x
set-variable' to set it.  This prompts for the variable name in the
minibuffer (with completion), and then prompts for a Lisp expression
for the new value using the minibuffer a second time.  For example,

     M-x set-variable RET fill-column RET 75 RET

sets `fill-column' to 75, like executing the Lisp expression

     (setq fill-column 75)

   Setting variables in this way, like all means of customizing Emacs
except where explicitly stated, affects only the current Emacs session.


File: emacs,  Node: Edit Options,  Next: Locals,  Prev: Examining,  Up: Variables

Editing Variable Values
-----------------------

`M-x list-options'
     Display a buffer listing names, values and documentation of all
     options.

`M-x edit-options'
     Change option values by editing a list of options.

   `M-x list-options' displays a list of all Emacs option variables, in
an Emacs buffer named `*List Options*'.  Each option is shown with its
documentation and its current value.  Here is what a portion of it
might look like:

     ;; exec-path:
     ("." "/usr/local/bin" "/usr/ucb" "/bin" "/usr/bin" "/u2/emacs/etc")
     *List of directories to search programs to run in subprocesses.
     Each element is a string (directory name)
     or nil (try the default directory).
     ;;
     ;; fill-column:
     75
     *Column beyond which automatic line-wrapping should happen.
     Automatically becomes local when set in any fashion.
     ;;

   `M-x edit-options' goes one step further and immediately selects the
`*List Options*' buffer; this buffer uses the major mode Options mode,
which provides commands that allow you to point at an option and
change its value:

`s'
     Set the variable point is in or near to a new value read using the
     minibuffer.

`x'
     Toggle the variable point is in or near: if the value was `nil',
     it becomes `t'; otherwise it becomes `nil'.

`1'
     Set the variable point is in or near to `t'.

`0'
     Set the variable point is in or near to `nil'.

`n'
`p'
     Move to the next or previous variable.


File: emacs,  Node: Locals,  Next: File Variables,  Prev: Edit Options,  Up: Variables

Local Variables
---------------

`M-x make-local-variable'
     Make a variable have a local value in the current buffer.

`M-x kill-local-variable'
     Make a variable use its global value in the current buffer.

`M-x make-variable-buffer-local'
     Mark a variable so that setting it will make it local to the
     buffer that is current at that time.

   You can make any variable "local" to a specific Emacs buffer.  This
means that the variable's value in that buffer is independent of its
value in other buffers.  A few variables are always local in every
buffer.  All other Emacs variables have a "global" value which is in
effect in all buffers that have not made the variable local.

   Major modes always make the variables they set local to the buffer.
This is why changing major modes in one buffer has no effect on other
buffers.

   `M-x make-local-variable' reads the name of a variable and makes it
local to the current buffer.  Further changes in this buffer will not
affect others, and changes in the global value will not affect this
buffer.

   `M-x make-variable-buffer-local' reads the name of a variable and
changes the future behavior of the variable so that it automatically
becomes local when it is set.  More precisely, once you have marked a
variable in this way, the usual ways of setting the variable will
automatically invoke `make-local-variable' first.  We call such
variables "per-buffer" variables.

   Some important variables have been marked per-buffer already.  They
include `abbrev-mode', `auto-fill-function', `case-fold-search',
`comment-column', `ctl-arrow', `fill-column', `fill-prefix',
`indent-tabs-mode', `left-margin',
`mode-line-format', `overwrite-mode', `selective-display-ellipses',
`selective-display', `tab-width', and `truncate-lines'.  Some other
variables are always local in every buffer, but they are used for
internal purposes.

   Note: the variable `auto-fill-function' was formerly named
`auto-fill-hook'.

   If you want that a variable ceases to be local to the current
buffer, call `M-x kill-local-variable' and provide the name of a
variable to the prompt.  The global value of the variable is again in
effect in this buffer.  Setting the major mode kills all the local
variables of the buffer.

   To set the global value of a variable, regardless of whether the
variable has a local value in the current buffer, you can use the Lisp
function `setq-default'.  It works like `setq'.  If there is a local
value in the current buffer, the local value is not affected by
`setq-default'; thus, the new global value may not be visible until
you switch to another buffer.  For example,

     (setq-default fill-column 75)

`setq-default' is the only way to set the global value of a variable
that has been marked with `make-variable-buffer-local'.

   Programs can look at a variable's default value with
`default-value'.  This function takes a symbol as an argument and
returns its default value.  The argument is evaluated; usually you
must quote it explicitly.  For example,

     (default-value 'fill-column)


File: emacs,  Node: File Variables,  Prev: Locals,  Up: Variables

Local Variables in Files
------------------------

   A file can contain a "local variables list", which specifies the
values to use for certain Emacs variables when that file is edited.
Visiting the file checks for a local variables list and makes each
variable in the list local to the buffer in which the file is visited,
with the value specified in the file.

   A local variables list goes near the end of the file, in the last
page.  (It is often best to put it on a page by itself.)  The local
variables list starts with a line containing the string `Local
Variables:', and ends with a line containing the string `End:'.  In
between come the variable names and values, one set per line, as
`VARIABLE: VALUE'.  The VALUEs are not evaluated; they are used
literally.

   The line which starts the local variables list does not have to say
just `Local Variables:'.  If there is other text before `Local
Variables:', that text is called the "prefix", and if there is other
text after, that is called the "suffix".  If a prefix or suffix are
present, each entry in the local variables list should have the prefix
before it and the suffix after it.  This includes the `End:' line.
The prefix and suffix are included to disguise the local variables list
as a comment so the compiler or text formatter  will ignore it.  If
you do not need to disguise the local variables list as a comment in
this way, there is no need to include a prefix or a suffix.

   Two "variable" names are special in a local variables list: a value
for the variable `mode' sets the major mode, and a value for the
variable `eval' is simply evaluated as an expression and the value is
ignored.  These are not real variables; setting them in any other
context does not have the same effect.  If `mode' is used in a local
variables list, it should be the first entry in the list.

   Here is an example of a local variables list:

     ;;; Local Variables: ***
     ;;; mode:lisp ***
     ;;; comment-column:0 ***
     ;;; comment-start: ";;; "  ***
     ;;; comment-end:"***" ***
     ;;; End: ***

   Note that the prefix is `;;; ' and the suffix is ` ***'.  Note also
that comments in the file begin with and end with the same strings.
Presumably the file contains code in a language which is enough like
Lisp for Lisp mode to be useful but in which comments start and end
differently.  The prefix and suffix are used in the local variables
list to make the list appear as several lines of comments when the
compiler or interpreter for that language reads the file.

   The start of the local variables list must be no more than 3000
characters from the end of the file, and must be in the last page if
the file is divided into pages.  Otherwise, Emacs will not notice it is
there.  The purpose is twofold: A stray `Local Variables:' not in the
last page does not confuse Emacs, and Emacs never needs to search a
long file that contains no page markers and has no local variables
list.

   You may be tempted to turn on Auto Fill mode with a local variable
list.  That is inappropriate.  Whether you use Auto Fill mode or not is
a matter of personal taste, not a matter of the contents of particular
files.  If you want to use Auto Fill, set up major mode hooks with your
`.emacs' file to turn it on (when appropriate) for you alone (*note
Init File::.).  Don't try to use a local variable list that would
impose your taste on everyone working with the file.

   Lucid GNU Emacs allows you to specify local variables in the first
line of a file, in addition to specifying them in the `Local variables'
section at the end of a file.

   If the first line of a file contains two occurences of ``-*-'',
Emacs uses the information between them to determine what the major
mode and variable settings should be.  For example, these are all
legal:

         ;;; -*- mode: emacs-lisp -*-
         ;;; -*- mode: postscript; version-control: never -*-
         ;;; -*- tags-file-name: "/foo/bar/TAGS" -*-

   For historical reasons, the syntax ``-*- modename -*-'' is allowed
as well, for example, you can use:

         ;;; -*- emacs-lisp -*-

   The variable `enable-local-variables' controls the use of local
variables lists in files you visit.  The value can be `t', `nil' or
something else.  A value of `t' means local variables lists are
obeyed; `nil' means they are ignored; anything else means query.

   The command `M-x normal-mode' always obeys local variables lists
and ignores this variable.


File: emacs,  Node: Keyboard Macros,  Next: Key Bindings,  Prev: Variables,  Up: Customization

Keyboard Macros
===============

   A "keyboard macro" is a command defined by the user to abbreviate a
sequence of keys.  For example, if you discover that you are about to
type `C-n C-d' forty times, you can speed your work by defining a
keyboard macro to invoke `C-n C-d' and calling it with a repeat count
of forty.

`C-x ('
     Start defining a keyboard macro (`start-kbd-macro').

`C-x )'
     End the definition of a keyboard macro (`end-kbd-macro').

`C-x e'
     Execute the most recent keyboard macro (`call-last-kbd-macro').

`C-u C-x ('
     Re-execute last keyboard macro, then add more keys to its
     definition.

`C-x q'
     When this point is reached during macro execution, ask for
     confirmation (`kbd-macro-query').

`M-x name-last-kbd-macro'
     Give a command name (for the duration of the session) to the most
     recently defined keyboard macro.

`M-x insert-kbd-macro'
     Insert in the buffer a keyboard macro's definition, as Lisp code.

   Keyboard macros differ from other Emacs commands in that they are
written in the Emacs command language rather than in Lisp.  This makes
it easier for the novice to write them, and makes them more convenient
as temporary hacks.  However, the Emacs command language is not
powerful enough as a programming language to be useful for writing
anything general or complex.  For such things, Lisp must be used.

   You define a keyboard macro by executing the commands which are its
definition.  Put differently, as you are defining a keyboard macro, the
definition is being executed for the first time.  This way, you see
what the effects of your commands are, and don't have to figure them
out in your head.  When you are finished, the keyboard macro is
defined and also has been executed once.  You can then execute the same
set of commands again by invoking the macro.

* Menu:

* Basic Kbd Macro::     Defining and running keyboard macros.
* Save Kbd Macro::      Giving keyboard macros names; saving them in files.
* Kbd Macro Query::     Keyboard macros that do different things each use.


File: emacs,  Node: Basic Kbd Macro,  Next: Save Kbd Macro,  Prev: Keyboard Macros,  Up: Keyboard Macros

Basic Use
---------

   To start defining a keyboard macro, type `C-x ('
(`start-kbd-macro').  From then on, anything you type continues to be
executed, but also becomes part of the definition of the macro.  `Def'
appears in the mode line to remind you of what is going on.  When you
are finished, the `C-x )' command (`end-kbd-macro') terminates the
definition, without becoming part of it.

   For example

     C-x ( M-f foo C-x )

defines a macro to move forward a word and then insert `foo'.

   You can give `C-x )' a repeat count as an argument, in which case it
repeats the macro that many times right after defining it, but defining
the macro counts as the first repetition (since it is executed as you
define it).  If you give `C-x )' an argument of 4, it executes the
macro immediately 3 additional times.  An argument of zero to `C-x e'
or `C-x )' means repeat the macro indefinitely (until it gets an error
or you type `C-g').

   Once you have defined a macro, you can invoke it again with the
`C-x e' command (`call-last-kbd-macro').  You can give the command a
repeat count numeric argument to execute the macro many times.

   To repeat an operation at regularly spaced places in the text,
define a macro and include as part of the macro the commands to move
to the next place you want to use it.  For example, if you want to
change each line, you should position point at the start of a line,
and define a macro to change that line and leave point at the start of
the next line.  Repeating the macro will then operate on successive
lines.

   After you have terminated the definition of a keyboard macro, you
can add to the end of its definition by typing `C-u C-x ('.  This is
equivalent to plain `C-x (' followed by retyping the whole definition
so far.  As a consequence it re-executes the macro as previously
defined.


File: emacs,  Node: Save Kbd Macro,  Next: Kbd Macro Query,  Prev: Basic Kbd Macro,  Up: Keyboard Macros

Naming and Saving Keyboard Macros
---------------------------------

   To save a keyboard macro for longer than until you define the next
one, you must give it a name using `M-x name-last-kbd-macro'.  This
reads a name as an argument using the minibuffer and defines that name
to execute the macro.  The macro name is a Lisp symbol, and defining
it in this way makes it a valid command name for calling with `M-x' or
for binding a key to with `global-set-key' (*note Keymaps::.).  If you
specify a name that has a prior definition other than another keyboard
macro, Emacs prints an error message and nothing is changed.

   Once a macro has a command name, you can save its definition in a
file.  You can then use it in another editing session.  First visit
the file you want to save the definition in.  Then use the command

     M-x insert-kbd-macro RET MACRONAME RET

This inserts some Lisp code that, when executed later, will define the
same macro with the same definition it has now.  You need not
understand Lisp code to do this, because `insert-kbd-macro' writes the
Lisp code for you.  Then save the file.  You can load the file with
`load-file' (*note Lisp Libraries::.).  If the file you save in is
your initialization file `~/.emacs' (*note Init File::.) then the
macro will be defined each time you run Emacs.

   If you give `insert-kbd-macro' a prefix argument, it creates
additional Lisp code to record the keys (if any) that you have bound
to the keyboard macro, so that the macro is reassigned the same keys
when you load the file.


File: emacs,  Node: Kbd Macro Query,  Prev: Save Kbd Macro,  Up: Keyboard Macros

Executing Macros with Variations
--------------------------------

   You can use `C-x q' (`kbd-macro-query'), to get an effect similar
to that of `query-replace'.  The macro asks you  each time whether to
make a change.  When you are defining the macro, type `C-x q' at the
point where you want the query to occur.  During macro definition, the
`C-x q' does nothing, but when you invoke the macro, `C-x q' reads a
character from the terminal to decide whether to continue.

   The special answers to a `C-x q' query are SPC, DEL, `C-d', `C-l'
and `C-r'.  Any other character terminates execution of the keyboard
macro and is then read as a command.  SPC means to continue.  DEL
means to skip the remainder of this repetition of the macro, starting
again from the beginning in the next repetition.  `C-d' means to skip
the remainder of this repetition and cancel further repetition.  `C-l'
redraws the screen and asks you again for a character to specify what
to do.  `C-r' enters a recursive editing level, in which you can
perform editing which is not part of the macro.  When you exit the
recursive edit using `C-M-c', you are asked again how to continue with
the keyboard macro.  If you type a SPC at this time, the rest of the
macro definition is executed.  It is up to you to leave point and the
text in a state such that the rest of the macro will do what you want.

   `C-u C-x q', which is `C-x q' with a numeric argument, performs a
different function.  It enters a recursive edit reading input from the
keyboard, both when you type it during the definition of the macro, and
when it is executed from the macro.  During definition, the editing
you do inside the recursive edit does not become part of the macro.
During macro execution, the recursive edit gives you a chance to do
some particularized editing.  *Note Recursive Edit::.